<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
	<meta http-equiv="content-type" content="text/html;charset=utf-8" />
	<title>Allegro Stuff</title>
	<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<!-- menu -->
	<div id="navmain">
	<ul>
		<li><a href="index.html">Overview</a></li>
		<li><a href="install.html">Installation</a></li>
		<li><a href="config.html">Configurator</a></li>
		<li><a href="animation.html">Animation</a></li>
		<li><a href="framework.html">Framework</a></li>
		<li><a href="tranzam.html">Tutorial</a></li>
	</ul>
	</div>
	<div id="navsub">
	<ul>
		<li><a href="#structure">Structure</a></li>
		<li><a href="#files">Files</a></li>
		<li><a href="#project">Compiling</a></li>
		<li style="display:none"><a href="#samples">Samples</a></li>
		<li style="display:none"><a href="#debug">Debugging</a></li>
		<li>Code Templates
		<ul>
		<li><a href="#code2">Configurator</a></li>
		<li><a href="#code1">Animation</a></li>
		<li><a href="#code3">Anim/Config</a></li>
		<li><a href="#code4">Framework</a></li>
		</ul></li>
	</ul><span class="smallprint">This menu will stay fixed with a proper browser.</span>
	<p>
	 <a href="http://jigsaw.w3.org/css-validator/">
	  <img style="border:0;width:88px;height:31px"
		   src="http://jigsaw.w3.org/css-validator/images/vcss" 
		   alt="Valid CSS!" />
	 </a>
	</p>
	<p>
      <a href="http://validator.w3.org/check?uri=referer"><img
          src="http://www.w3.org/Icons/valid-xhtml10"
          alt="Valid XHTML 1.0!" height="31" width="88" /></a>
    </p>
<p><a href="http://www.bloggerheads.com/bbc/"><img src="http://www.bloggerheads.com/bbc/bbc.gif" width="90" height="45"  
alt="Click here to find out why." /></a></p>
<p><a href="http://retrospec.sgn.net" ><img src="retrospec.gif" width="150" alt="Fine games" /></a></p>
	</div>
<!-- menu -->

	<div id="main">
		<a name="structure"></a>
		<h1>Structure</h1>
<p>On unzipping, the following directory structure will exist (the top level being the directory 'axl_projects'):</p>
<ul>
<li><strong>docs</strong>	: this documentation</li>
<li><strong>tests</strong>	: samples/tutorials for all the libraries</li>
<li><strong>extern</strong>		: the external libraries used (tinyXML<span style="display:none">, fblend</span>)</li>
</ul>
		<a name="files"></a>
		<h1>Library Files</h1>
For each library component you want to use, there is one c++ code file and one header file, located in the root directory, that you need to include in your project:
<ul>
<li><strong>Animation: </strong>axl_animations.cpp/axl_animations.h</li>
<li><strong>Configurator: </strong>axl_config.cpp/axl_config.h</li>
<li><strong>Framework: </strong>axl_framework.cpp/axl_framework.h</li>
<li style="display:none"><strong>Sprite   : </strong>sprites.cpp/sprites.h</li>
</ul>
Also, each header file automatically includes the file axl.h. This file contains all the optimisations you might want to apply to the various modules. Refer to the 'Optimising' section of each module (from the main menu) - or just open the file and read it. The optimisations apply to the Animation and Framework modules.
<p>Because each library is self-sufficient you can delete any of the pairs of files you are not interested in. 
Remember though the Framework requires Animation and Configurator so all files are required if using the Framework.</p>
<p>A few external libraries are also required (though included with the download):</p><ul><li><strong>tinyXML: </strong> is a sourceforge library written in ANSI compatible C and is a 
library for handling XML files. It is required by the library</li>
<li style="display:none"><strong>FBlend: </strong> Used by the animation library only. This is another sourceforge library but specific to Allegro 
and allows much faster blended bitmap drawing than the built in blender functions (for 
transparency, additive, subtractive drawing). Although not required, if present it will be 
compiled in and speeds up execution of the fade routines.</li></ul>
<p><span style="display:none">Feel free to delete fblend if not required, or update either with newer versions. </span>
This release includes <span style="display:none">version 0.5beta1 of FBlend and</span> version 2.3.4 of tinyXML.</p>
<p><strong>WARNING for Windows Users: </strong>The current stable 4.2 (and below) version of allegro has bugs that prevent subbitmaps (i.e. the Animation module uses these if you are using sheet graphics) from being displayed if your parent bitmap is either a system or a video bitmap, and crashes your program if you try to delete a subbitmap (e.g. deleting animation objects that use sheet graphics) that is a system bitmap. Included in the download is an update that fixes these bugs that should be available in the next stable or a future CVS release. Simply use this DLL and all will be well. Also put the gfx.h file in your allegro include directory.<br/><br/>This DLL also includes code changes to allow hardware acceleration of the stretch functions (currently it is only non-stretching functions that use hardware acceleration). However, one bug found is if you stretch video bitmaps (system and memory bitmaps are ok) then you *may* encounter a 'halo' effect round the bitmap where the mask colour is showing. However it is fixed by updating your video driver. This problem was found on a few nvidia cards with older drivers.</p>
		<a name="project"></a>
		<h1>Installation for Windows using MSVC/MinGW/Dev-C++</h1>
		<p>If you already have <span style="display:none">Fblend and </span>tinyXML then ignore this set of instructions.<ol>
<li style="display:none">If using MSVC copy the extern\fblend.lib and extern\tinyxml.lib files to your lib directory (exclude fblend if you do not wish to use it)</li>
<li>If using MSVC copy the extern\tinyxml.lib file to your lib directory</li>
<li>If using minGW/Dev-c++ follow step 1 but use the <span style="display:none">fblend.a and</span> tinyxml.a file</li>
<li style="display:none">Copy the extern\fblend_minimum\fblend.h file to your include directory</li>
<li>Copy the extern\tinyxml_minimum\*.h files to your include directory</li>
</ol>
If you wish, instead of using the tinyxml library file you can simply add the four *.cpp files from the extern\tinyxml_minimum
directory to your project. These files constitute the whole of tinyxml and allow easier debugging/fault fixing. You can also ignore the above
instructions and simply modify your IDE to search the extern directories for lib/include files.
		</p>

		<h1>Installation for Other Systems</h1>
		<p><ol>
<li style="display:none">FBlend: If you are planning on using fblend for the faster fade routines then you will need to download and install fblend
yourself as the library is too big to include here. Otherwise simply do nothing as the animation library works without it</li>
<li>TinyXML: This is a small portable library with no other dependencies. Either include the *.cpp files in your project 
or compile and pack the *.cpp files into a library file</li>
<li>If using your compiled files then copy the relevant header and library files to your lib/include directories</li>
</ol>
		</p>
		
		<h1>Quick Compilation Test</h1>
		<h2>Configurator</h2>
		<ol>
<li>Firstly (if using Windows) run the tests\config\example1.exe demo to see what the library can do</li>
<li>Create your allegro project as normal</li>
<li>To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above) before the allegro library (alleg.lib/liballeg.a)</li>
<li>To your project add axl_config.cpp from the axl_projects root directory</li>
<li>To your project add the tests\config\example1\main.cpp to your project and compile</li>
</ol>
		<h2>Animation</h2>
		<ol>
<li>Firstly (if using Windows) run the tests\animation\example1.exe demo to see what the library can do</li>
<li>Create your allegro project as normal</li>
<li style="display:none">To the external library files add fblend.lib/fblend.a (if used) and tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above)
</li>
<li>To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above)
</li>
<li>To your project add axl_animation.cpp from the axl_projects root directory</li>
<li>To your project add the tests\animation\example1\main.cpp to your project and compile</li>
</ol>
		<h2>Framework</h2>
		<ol>
<li>Firstly (if using Windows) run the tests\framework\example1.exe demo. This is just a quick text output showing how the FPS loop handles events</li>
<li>Create your allegro project as normal</li>
<li>To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above) before the allegro library (alleg.lib/liballeg.a)
</li>
<li>To your project add axl_framework.cpp from the axl_projects root directory</li>
<li>To your project add axl_animation.cpp from the axl_projects root directory</li>
<li>To your project add axl_config.cpp from the axl_projects root directory</li>
<li>To your project add the tests\framework\example1\main.cpp to your project and compile</li>
</ol>
		<h2>Combined</h2>
All the libraries work together. To see this a number of examples exist:
<ol>
<li>Firstly (if using windows) run the tests\animation\example2.exe. This example is exactly the same as 
the animation example1 except instead of using custom code to startup allegro, the Configurator library is used. The improvement 
can be seen by no allegro startup code in the main.cpp code and the ability to change settings and the way the display is rendered via the XML. 
Only the startup (graphics mode selection, installation of devices, etc) is done by Configurator.</li>
<li>Secondly (if using windows) run the tests\animation\example3.exe. This example is the same as the animation example 1 and 2 but builds on example 2 byt
doing all of the FPS loops, allowing the system to run using triple, double, paging, etc.
</ol>
For the combined tests you need to include the relevant files mentioned above (e.g. tinyXML and the main.cpp from the example directory). For the first combined test (animation\example 2) you need to include the Configurator source file (axl_config.cpp) with the animation source file (axl_animation.cpp). For the second combined example (animation\example 3) you need all the source files (axl_framework.cpp, axl_config.cpp, axl_animation.cpp) plus the main.cpp. Further details on the examples are found in the 'Examples' section of each help topic in the main menu.

		<p><em>Alternatively Dev-C++ and VS2005 projects have already been set up to do this and are found in the tests directory for all examples. Note: for Dev-C++ users the full path of the .a library files has to be stored in the project file, so on loading the projects for the first time, edit the compiler settings and change the absolute path to wherever it is stored. <span style="display:none">Also, FBlend is not included by default, to add this, add the .a or .lib file to the project make file. This needs to be included before the Allegro library, otherwise link errors will result.</span></em></p>
		<h1>Code Templates</h1>
		Below are example minimal code templates to get you started. You best approach is to read and use the samples in the test directories. 
		<a name="code2"></a>
		<h2>Configurator Only</h2>
		<div class="codeblock code">
#include "axl_config.h"
using namespace AXL_Projects;
using namespace std;

int main()
{
  Configuration* myConfig;
  myConfig=new Configuration("config.xml");
  if(Configuration::GlobalErrorString!="")
  {
   	//some kind of nice exit
   	return 1;
  }
  
  //start allegro and set up everything
  myConfig.AllegroStart();
  
  //we are now in a graphics mode and have access to everything such as:
  int lives=1;
  float g;
  string author;
  lives=myConfig->GetCustom("lives",-1);
  g=myConfig->GetCustom("gravity",-9.8F);
  author=myConfig->GetCustom("author","george dawes");
  myConfig->SetCustom("lives",lives+1);
  myConfig->SetCustom("badger","badger badger badger");
  myConfig->FlushCustom();	//i'd rather not wait until exit to write to file
  
  //use some stuff
  int fps=myConfig->CapsSystem.fps;
  string windowmode=myConfig->CapsGraphics.WindowMode;
  
  //change some settings from an options menu
  myConfig->CapsGraphics.WindowMode="fullscreen";
  
  //below will write all main and custom settings back to the file
  //if we have set the flag in the XML to do it, otherwise, 
  //simply call myConfig->FlushCustom() and myConfig->FlushMain() 				
  delete myConfig;
  	
  //shouldn't call exit in a destructor, 
  //just in case the badgers get you
  allegro_exit();
  return 0;
}
END_OF_MAIN()
</div>
		<a name="code1"></a>

		
		<h2>Animation Only</h2>
		<div class="codeblock code">
#include "axl_animations.h"
using namespace AXL_Projects;

int main()
{
  //whatever you do normally
	allegro_init();
	install_timer();
	install_keyboard();
	set_color_depth(32);
	if(set_gfx_mode(GFX_AUTODETECT,640,480,0,0)<0) 
	{
	 //nice failure exit message
	 return 1;
	};
	
	//animation set up
	AnimationLibrary* GameLibrary;

	GameLibrary=new AnimationLibrary();
	if(!GameLibrary->LoadAnimations("myfile.xml"))
	{
		delete GameLibrary;
		//nice failure exit message
		return 1;
	}

	//debug code that outputs every graphic to the screen	
	//GameLibrary->draw();
	
	//sample code to get an animation via creating a new object
	Animation* FuelAnimation=new Animation(GameLibrary,"fuelfull");
	draw_sprite(screen, FuelAnimation->ReadOnly_CurrentItem, 0,0);
	
	//sample code to get an animation once the object is created
	fuelAnimation->SetNewAnimation("fuelempty");
	
	//exit code
	delete FuelAnimation;
	delete GameLibrary;
	
	readkey();
	allegro_exit();
	return 0;
}
END_OF_MAIN()
</div>
		<a name="code3"></a>
		<h2>Combined Configurator and Animation</h2>
		<div class="codeblock code">
#include "axl_animation.h"
#include "axl_config.h"
using namespace AXL_Projects;
using namespace std;

int main()
{
  Configuration* myConfig;
  myConfig=new Configuration("config.xml");
  if(Configuration::GlobalErrorString!="")
  {
   	//some kind of nice exit
   	return 1;
  }
  
  //start allegro and set up everything
  if(myConfig.AllegroStart()==0)
  {
   	//some kind of nice exit
   	return 1;
  }

  //animation set up. need allegro up and running first so bitmaps are loaded correctly
  AnimationLibrary* GameLibrary;

  GameLibrary=new AnimationLibrary();
  if(!GameLibrary->LoadAnimations("myfile.xml"))
  {
  	delete GameLibrary;
	  //nice failure exit message
	  return 1;
  }

  //sample code to get an animation via creating a new object
  Animation* FuelAnimation=new Animation(GameLibrary,"fuelfull");
	
  string author;
	int lives=3;
  author=myConfig->GetCustom("author","george dawes");
  myConfig->SetCustom("lives",lives+1);
  myConfig->FlushCustom();	//i'd rather not wait until exit to write to file
  //use some stuff and change, maybe through a menu
  int fps=myConfig->CapsSystem.fps;
  string windowmode=myConfig->CapsGraphics.WindowMode;
	
  //draw our sprite
  draw_sprite(screen, FuelAnimation->ReadOnly_CurrentItem, 0,0);
	
  //sample code to get an animation once the object is created
  fuelAnimation->SetNewAnimation("fuelempty");

  //exit code
  delete myConfig;
  delete FuelAnimation;
  delete GameLibrary;

  readkey();
  allegro_exit();
  return 0;
  
}
END_OF_MAIN()
</div>
		<a name="code4"></a>
		<h2>Framework using Animation and Configuration</h2>
		<div class="codeblock code">
#include "axl_framework.h"	//this opens axl_config.h/axl_animation.h for us

using namespace AXL_Projects;

//main game variables
static Framework* GameFramework;			//framework
static AnimationLibrary* GameLibrary;		//our graphics library
static Configuration* GameConfiguration;	//our configuration object

//if we want to show the FPS, this holds it
extern volatile int TimerCurrentFPS;	

//forward declarations as this sample isn't using a header file
//hooks to pass to framework for the various parts of the game
bool LogicStartup();
bool DrawingStartup();
bool LogicMenu();
bool DrawingMenu();
bool LogicGame();
bool DrawingGame();
bool LogicGameOver();
bool DrawingGameOver();
bool OverrideLogic1();
bool OverrideDrawing1();
void SetupGame();

void EndGame();
void DoMenu(int speed);

int main(void)
{
	//create our framework, load animations, initialise buffers,
	//on leaving, unless errors, we will be in graphics mode
	GameFramework=new Framework("config.xml","animations.xml");

	if(Configuration::GlobalErrorString!="")
	{
		delete GameFramework;
		allegro_message(Configuration::GlobalErrorString.c_str());
	}
	else
	{
		//any initialisation needed before the game starts
		//usually assign variables to the configurator, animation library, etc.
		SetupGame();
		
		//can just use NULL if any are not required as they are
		//arbitrary anyway, they are called by the flag you set.
		if( !GameFramework->StartGameLoop(
				LogicStartup,DrawingStartup,
				LogicMenu,DrawingMenu,
				LogicGame,DrawingGame,
				LogicGameOver,DrawingGameOver,true) ) 
		{
			//destroy everything, clean up memory and bitmaps, stop timers, etc.
			//exit is text mode
			delete GameFramework;
			allegro_message("Failed to run game loop. Check config.log");
		}
		else 
		{
			//do any clean up we want, e.g. our dynamic variables for Animations, etc
			EndGame();
			//destroy everything, clean up memory and bitmaps, stop timers, etc.
			//exit is text mode
			delete GameFramework;
		}
	}
	allegro_exit();
	return 0;
}
END_OF_MAIN();

bool LogicStartup()
{
  //to change the logic/drawing call the change timer function with
	//the relevant name (these correspond to the functions passed in
	GameFramework->ChangeTimerType(GAME_MENU);
	
	//if we want to set an override, e.g. instead of coding lots of stuff here
	//or putting in lots of case statements we can temporarily swap the timer type
	//(sort of like ChangeTimerType but on returning true it returns back to the
	//original logic/drawing pair
	//SetAutoGameLoopOverride(OverrideLogic1,OverrideDrawing1);
	
	//return true;	//return and exit the loop
	return false;	//return normally
}

bool DrawingStartup()
{
	//DrawingSurface is the SCREEN sized drawing buffer
	//the system handles the buffering mode (paging, triple, double, etc)
	//and does all the swapping for you. you still need to clear it if you need to
	//the system calls each logic/drawing pair at the correct time to maintain FPS
	clear_to_color(GameFramework->DrawingSurface,makecol(0,0,0));

	//return true;	//return and exit the loop
	return false;
}

//the other functions are to be coded exactly as LogicGStartup
bool LogicMenu() { return false; }
bool DrawingMenu(){ return false; }
bool LogicGame() { return false; }
bool DrawingGame(){ return false; }
bool LogicGameOver() { return false; }
bool DrawingGameOver(){ return false; }


//our helper functions
void SetupGame()
{
	//we are in a graphics mode, so grab everything needed
	GameLibrary=GameFramework->GetGraphicsLibrary();
	GameConfiguration=GameFramework->GetConfiguration();
	
	//initialise animations, etc. exactly as animation/configuration examples, e.g.
	//MainAnimation=new Animation(GameLibrary,"ufo");
	//CollisionAnimation=new Animation(GameLibrary,"fuel");
	//AnimationLibraryFrames* af=GameLibrary->GetAnimation("logo");
	//LogoAnimation=new Animation(GameLibrary,af);
	//LogoAnimationSimple=GameLibrary->GetFirstGraphic("logo");
}

void EndGame()
{
	//only delete the stuff we create
	//the framework deletes the drawing buffers, animation, framework, configuration
	//delete MainAnimation;
	//delete CollisionAnimation;
	//delete LoopAnimation
}
</div>

<p>Now select which library part you wish to learn about from the left hand menu, 'Framework', 'Animation', 'Configurator'</p> 
</body>
</html>
